home *** CD-ROM | disk | FTP | other *** search
/ PC Graphics Unleashed / PC Graphics Unleashed.iso / polyray / plydoc / quickref.txt < prev    next >
Encoding:
Text File  |  1994-03-16  |  13.5 KB  |  414 lines
  1. This file contains an extremely abbreviated description of the command line
  2. flags, initialization file statements, and data file declarations for Polyray.
  3. See "polyray.doc" for more details.
  4.  
  5. Syntax:
  6.  
  7.    polyray datafile [ options ]
  8.  
  9. Command line options:
  10.  
  11.    -a mode         Antialiasing (0=none,1=corner average,2-4=adaptive)
  12.    -b pixels       pixels calculated between file flushes
  13.    -B              Flush the output file every scan line
  14.    -d              Generate a depth file instead of an image file
  15.    -o filename     Output file name (default "out.tga")
  16.    -p bits/pixel   Number of bits per pixel 8/16/24/32 (default 16)
  17.    -P pallette     Which pallette to use [0=grey, 1=666, 2=884]
  18.    -Q              Abort if any key is hit during trace
  19.    -q flags        Turn on/off various global shading options
  20.    -r renderer     Which rendering method [0=raytrace, 1=scan convert,
  21.                    2=wireframe, 3=raw triangle information,4=uv triangles]
  22.    -R              Resume an interrupted trace
  23.    -s samples      # of samples per pixel when performing focal blur
  24.    -t status_vals  Status display type [0=none,1=totals,2=line,3=pixel].
  25.    -T threshold    Threshold to start oversampling (default 0.2)
  26.    -u              Write the output file in uncompressed form
  27.    -v              Trace from bottom to top
  28.    -V mode         Display mode while tracing (0=none,1-5=8bit,6-10=16,11-15=24)
  29.    -W              Wait for key before clearing display
  30.    -x columns      Set the x resolution
  31.    -y lines        Set the y resolution
  32.    -z start_line   Start a trace at a specified line
  33.  
  34. Initialization file ("polyray.ini") keywords:
  35.  
  36.    abort_test       true/false/on/off
  37.    alias_threshold  [Value to cause adaptive anitaliasing to start]
  38.    antialias        none/filter/adaptive1/adaptive2
  39.    clustersize      [# of objects stored in a slab]
  40.    display          none/vga1...vga5/hicolor1...hicolor5/truecolor1...truecolor5
  41.    max_level        [max depth of recursion]
  42.    max_samples      [# of samples when performing focal blur]
  43.    optimizer        none/slabs
  44.    pallette         884/666/grey
  45.    pixel_size       8/16/24/32
  46.    pixel_encoding   none/rle
  47.    renderer         ray_trace/scan_convert/wire_frame/raw_triangles/uv_triangles
  48.    shade_flags      [default/bit mask of flags, see section 1.7.1.4 of docs]
  49.    shadow_tolerance [miminum distance for blocking objects]
  50.    status           none/totals/line/pixel
  51.    warnings         on/off
  52.  
  53.    Any lines starting with "//" will be treated as comments & ignored.
  54.    Any lines surrounded with "/*" ... "*/" will be ignored
  55.  
  56. Input file syntax:
  57.  
  58.    [viewpoint statement]
  59.    [object declaration]
  60.    [conditional statement]
  61.    define token expression
  62.    define token [object declaration]
  63.    define token [surface declaration]
  64.    define token [texture declaration]
  65.    define token texture_map([a, b, texture1, texture2]
  66.                 ...
  67.                 [x, y, texturei, texturej])
  68.    define token particle { [particle declarations] }
  69.    define token transform { [rotate/translate/scale/shear statements] }
  70.    total_frames val
  71.    start_frame val
  72.    end_frame val
  73.    outfile "name"
  74.    outfile name
  75.    file_flush xxx
  76.    include "filename"
  77.    system(arg1, ..., argn)
  78.    background color
  79.    background expression
  80.    haze coeff, starting_distance, color
  81.    light color, location
  82.    light location
  83.    spot_light color, location, pointed_at, Tightness, Angle, Falloff
  84.    spot_light location, pointed_at
  85.    textured_light {
  86.       color color_expression
  87.       [sphere center, radius]
  88.       [rotate/translate/... statements]
  89.       }
  90.    directional_light color, direction
  91.    directional_light direction
  92.    depthmapped_light {
  93.       [ angle fexper ]
  94.       [ aspect fexper ]
  95.       [ at vexper ]
  96.       [ color expression ]
  97.       [ depth "depthfile.tga" ]
  98.       [ from vexper ]
  99.       [ hither fexper ]
  100.       [ up vexper ]
  101.       }
  102.  
  103. Expressions:
  104.    Floating point operators:
  105.       +, -, *, /, ^
  106.    Functions returning floats:
  107.       acos(x), asin(x), atan(x), atan2(x, y), ceil(x), cos(x), cosh(x),
  108.       degrees(x), exp(x), fabs(x), floor(x), fmod(x, y), heightmap(image, P),
  109.       indexed(image,P), legendre(l, m, x), ln(x), log(x), max(x, y), min(x, y),
  110.       noise(P), noise(P, o), noise(P, <p, n, o>), pow(x, y), radians(x),
  111.       sawtooth(x), sin(x), sinh(x), sqrt(x), tan(x), tanh(x), visible(V1, V2),
  112.       V1 . V2, |x|
  113.    Vector operators:
  114.       +, -, * (cross product, or float times a vector)
  115.    Functions returning vectors/colors:
  116.       brownian(P), brownian(P, S), color_wheel(x, y, z), dnoise(P),
  117.       dnoise(P, o), dnoise(P, <p, n, o>), rotate(V1, <xdeg, ydeg, zdeg>),
  118.       rotate(V1, V2, deg), reflect(V1, V2) trace(P, D)
  119.    Predefined variables:
  120.       u, v, x, y, z, P, W, N, I, start_frame, frame, end_frame
  121.    Image file manipulation:
  122.       environment("file1", "file2", ..., "file6")
  123.       image("file")
  124.       cylindrical_imagemap(image, V [, repeat flag])
  125.       planar_imagemap(image, V [, repeat flag])
  126.       spherical_imagemap(image, V [, repeat flag])
  127.       heightmap(image, V)
  128.       indexed_map(image, V [, repeat flag])
  129.       environment_map(V, environment)
  130.    Color map:
  131.       color_map([v0, v1, Color0, Color1]
  132.             [v2, v3, Color2, Color3]
  133.                 ...
  134.         [vx, vy, Colorx, Colory])
  135.       color_map([v0, v1, Color0, alpha0, Color1, alpha1]
  136.             [v2, v3, Color2, alpha2, Color3]
  137.                 ...
  138.         [vx, vy, Colorx, Colory, alphay])
  139.    String manipulation (build single string from a set of string,
  140.    numerical, or vector arguments):
  141.       concat(arg1, arg2, ..., arg3)
  142.  
  143. Viewpoint declaration:
  144.  
  145.     viewpoint {
  146.        [ from vexper ]                 // Default: <0, 0,-1>
  147.        [ at vexper ]                   // Default: <0, 0, 0>
  148.        [ up vexper ]                   // Default: <0, 1, 0>
  149.        [ angle fexper ]                // Default: 45
  150.        [ resolution fexper, fexper ]   // Default: 256x256
  151.        [ aspect fexper ]               // Default: 1.0
  152.        [ hither fexper ]               // Default: 1.0e-3
  153.        [ yon fexper ]                  // Default: 1.0e6
  154.        [ max_trace_depth fexper ]      // Default: 5
  155.        [ aperture fexper ]             // Default: 0
  156.        [ focal_distance fexper ]       // Default: distance between from & at
  157.        [ image_format fexper ]         // 0 = image, 1 = depth
  158.        [ pixelsize fexper ]            // valid: 8, 16, 24, 32
  159.        [ pixel_encoding fexper ]       // 0 = normal, 1 = RLE
  160.        [ antialias fexper ]            // 0 = none, 1 = filter, 2-4 = adaptive
  161.        [ antialias_threshold fexper ]  // Default: 0.02
  162.        }
  163.  
  164. Object declaration:
  165.  
  166.    object {
  167.       Shape declaration
  168.       [ texture declaration ]
  169.       [ Object modifier declaration ]
  170.       }
  171.  
  172. Shape Declarations:
  173.  
  174.    bezier subdivision_type, flatness_value,
  175.           u_subdivisions, v_subdivision,
  176.           [ 16 comma-separated vertices, i.e.
  177.              <x0, y0, z0>, <x1, y1, z1>, ..., <x15, y15, z15> ]
  178.  
  179.    blob threshold:
  180.       blob_component1
  181.       [, sphere <x, y, z>, strength, radius ]
  182.       [, cylinder <x0, y0, z0>, <x1, y1, z1>, strength, radius ]
  183.       [, plane <nx, ny, nz>, d, strength, distance ]
  184.  
  185.    box <x0, y0, z0>, <x1, y1, z1>
  186.  
  187.    cone <x0, y0, z0>, r0, <x1, y1, z1>, r1
  188.  
  189.    cylinder <x0, y0, z0>, <x1, y1, z1>, r
  190.  
  191.    disc <cx, cy, cz>, <nx, ny, nz>, r
  192.    disc <cx, cy, cz>, <nx, ny, nz>, ir, or
  193.  
  194.    function f(x,y,z)
  195.  
  196.    glyph contour_count,
  197.       contour num_points1, V11, ..., V1n
  198.       ...
  199.       contour num_pointsm, Vm1, ..., Vmn
  200.  
  201.    gridded "filename", object1 object2 ...
  202.  
  203.    height_field "filename"
  204.    smooth_height_field "filename"
  205.  
  206.    height_fn xsize, zsize, min_x, max_x, min_z, max_z, expression
  207.    height_fn xsize, zsize, expression
  208.    smooth_height_fn xsize, zsize, min_x, max_x, min_z, max_z, expression
  209.    smooth_height_fn xsize, zsize, expression
  210.  
  211.    lathe type, direction, total_vertices,
  212.       <vert1.x,vert1.y,vert1.z>
  213.       [, <vert2.x, vert2.y, vert2.z>]
  214.       [, etc. for total_vertices vertices]
  215.  
  216.    nurb u_order, u_vertices, v_order, v_vertices,
  217.     [u_knot1, ..., u_knot(u_order+u_vertices)],
  218.     [v_knot1, ..., v_knot(v_order+v_vertices)],
  219.     [[<vert(1,1)>, ..., <vert(1,v_order)>],
  220.      ...
  221.      [<vert(u_order,1)>, ..., <vert(u_order,v_order)>]]
  222.  
  223.    nurb u_order, u_vertices, v_order, v_vertices,
  224.     [[<vert(1,1)>, ..., <vert(1,v_order)>],
  225.      ...
  226.      [<vert(u_order,1)>, ..., <vert(u_order,v_order)>]]
  227.  
  228.    parabola <x0, y0, z0>, <x1, y1, z1>, r
  229.  
  230.    parametric <fx(u,v), fy(u,v), fz(u,v)>
  231.  
  232.    polygon total_vertices,
  233.       <vert1.x,vert1.y,vert1.z>
  234.       [, <vert2.x, vert2.y, vert2.z>]
  235.       [, etc. for total_vertices vertices]
  236.  
  237.    polynomial f(x,y,z)
  238.  
  239.    sphere <center.x, center.y, center.z>, radius
  240.  
  241.    sweep type, direction, total_vertices,
  242.       <vert1.x,vert1.y,vert1.z>
  243.       [, <vert2.x, vert2.y, vert2.z>]
  244.       [, etc. for total_vertices vertices]
  245.  
  246.    torus r0, r1, <center.x, center.y, center.z>, <dir.x, dir.y, dir.z>
  247.  
  248.    patch <v1.x,v1.y,v1.z>, <n1.x,n1.y,n1.z>, [ UV u1, v1, ]
  249.          <v2.x,v2.y,v2.z>, <n2.x,n2.y,n2.z>, [ UV u2, v2, ]
  250.          <v3.x,v3.y,v3.z>, <n3.x,n3.y,n3.z> [, UV u3, v3 ]
  251.  
  252.    object1 + object2  - Union
  253.    object1 * object2  - Intersection
  254.    object1 - object2  - Difference
  255.    object1 & object2  - Clipping
  256.    ~object1           - Inverse
  257.  
  258. Root solver declarations (for blobs, polynomials, splined lathes, and tori):
  259.  
  260.    root_solver Ferrari
  261.    root_solver Vieta
  262.    root_solver Sturm
  263.  
  264. Object modifier statements:
  265.  
  266.    translate <tx, ty, tz>
  267.    rotate <rx,ry,rz>
  268.    scale <sx,sy,sz>
  269.    shear yx, zx, xy, zy, xz, yz
  270.    shading_flags flag1+flag2+...
  271.    u_steps u
  272.    v_steps v
  273.    w_steps w
  274.    uv_steps u, v
  275.    uv_steps u, v, w
  276.    uv_bounds u0, u1, v0, v1
  277.    bounding_box <x0,y0,z0>, <x1,y1,z1>
  278.    displace expression
  279.  
  280. Shading flag values:
  281.  
  282.    1 = Shadow_Check, 2 = Reflect_Check, 4 = Transmit_Check,
  283.    8  = Two_Sides, 16 = UV_Check, 32 = Cast_Shadow
  284.  
  285.  
  286. Textures:
  287.    texture {
  288.       [ texture declaration ]
  289.       [ rotate/translate/scale/shear ]
  290.       }
  291.  
  292. Texture declarations:
  293.  
  294.    surface { [ surface declarations ] }
  295.    noise surface { [ surface declarations ] }
  296.    noise surface_sym
  297.    noise surface_sym { [ surface declarations ] }
  298.    special surface { [ surface declarations ] }
  299.    special surface_sym
  300.    special surface_sym { [ surface declarations ] }
  301.    checker texture1, texture2
  302.    hexagon texture1, texture2, texture3
  303.    layered texture1, texture2, ..., textureN
  304.    indexed fn, texture_map([a, b, texture1, texture2]
  305.                ...
  306.                [x, y, texturei, texturej])
  307.    indexed fn, texture_map_sym
  308.    summed fexper, texture1,
  309.       ...
  310.       fexper, texturen
  311.  
  312. Surface declarations:
  313.  
  314.    color <r, g, b>
  315.    ambient scale
  316.    ambient color, scale
  317.    diffuse scale
  318.    diffuse color, scale
  319.    specular color, scale
  320.    specular scale
  321.    reflection color, scale
  322.    reflection scale
  323.    transmission color, scale, ior
  324.    transmission scale, ior
  325.    microfacet kind angle
  326.  
  327. Microfacet kinds: Blinn, Cook, Gaussian, Phong, Reitz.
  328.  
  329. Special Surface declarations add the following to Surface declarations:
  330.  
  331.    position vexper     // Turbulence: P + x * (dnoise(P, o) - <0.5, 0.5, 0.5>)
  332.    normal vexper       // Bumps: N + x * (dnoise(P, o) - <0.5, 0.5, 0.5>)
  333.  
  334. Bumpmap declarations to use in the normal component of special surfaces:
  335.  
  336.       cylindrical_bumpmap(image, V [, bump size])
  337.       planar_bumpmap(image, V [, bump size])
  338.       spherical_bumpmap(image, V [, bump size])
  339.  
  340. Noise Surface declarations include all surface declarations plus:
  341.  
  342.    color_map(map_entries)
  343.    bump_scale fexper
  344.    frequency fexper
  345.    phase fexper
  346.    lookup_fn index
  347.    normal_fn index
  348.    octaves fexper
  349.    position_fn index
  350.    position_scale fexper
  351.    turbulence fexper
  352.  
  353. The output of the following function is passed through the lookup function,
  354. then into the color map.
  355.    nval = pos * position_scale + turbulence * noise(P, octaves);
  356.  
  357. Valid values for position_fn are:
  358.    0 - No position function used (default)
  359.    1 - X coordinate in object space
  360.    2 - X coordinate in world space
  361.    3 - Distance from z-axis
  362.    4 - Distance from the origin
  363.    5 - Radial measure (counter clockwise) around y-axis
  364.  
  365. Valid values for normal_fn are:
  366.    0 - No modification made to normal (default)
  367.    1 - Bumpy
  368.    2 - Rippled
  369.    3 - Dented
  370.  
  371. Valid values for lookup_fn are:
  372.    0 - Use nval directly
  373.    1 - sawtooth applied to nval
  374.    2 - sin function
  375.    3 - ramp function
  376.  
  377. Conditional processing:
  378.  
  379.    if (cexper)
  380.       [single declaration]
  381.  
  382.    if (cexper) {
  383.       [object/light/... declarations]
  384.       }
  385.    else {
  386.       [other object/light/... declarations]
  387.       }
  388.  
  389. Particles:
  390.  
  391.    particle { [particle_declarations] }
  392.    particle_sym
  393.    particle_sym { [particle_declarations] }
  394.  
  395.  
  396. Particle declarations:
  397.    birth expression           // Particles are born when exper is non-zero
  398.    count fexper               // # of objects to create when birth is non-zero
  399.    death expression           // Dies when the expression is non-zero
  400.    position vexper            // Starting position
  401.    velocity vexper            // Starting velocity
  402.    acceleration vexper        // Acceleration added every frame
  403.    avoid expression           // Any non-null expression invokes avoid
  404.    object object_sym          // Previously defined object
  405.  
  406. Particle variables:
  407.    P   - Current location of the particle
  408.    x   - X location of particle
  409.    y   - Y location of particle
  410.    z   - Z location of particle
  411.    I   - Current velocity of the particle
  412.    u   - Age of the particle
  413.  
  414.